﻿<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
  
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Getting Started with DocFX | DocFX website </title>
    <meta name="viewport" content="width=device-width">
    <meta name="title" content="Getting Started with DocFX | DocFX website ">
    <meta name="generator" content="docfx 2.37.0.0">
    
    <link rel="shortcut icon" href="../favicon.ico">
    <link rel="stylesheet" href="../styles/docfx.vendor.css">
    <link rel="stylesheet" href="../styles/docfx.css">
    <link rel="stylesheet" href="../styles/main.css">
    <meta property="docfx:navrel" content="../toc.html">
    <meta property="docfx:tocrel" content="toc.html">
    
    <meta property="docfx:rel" content="../">
    
  </head>
  <body data-spy="scroll" data-target="#affix" data-offset="120">
    <div id="wrapper">
      <header>
        
        <nav id="autocollapse" class="navbar navbar-inverse ng-scope" role="navigation">
          <div class="container">
            <div class="navbar-header">
              <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
              </button>
              
              <a class="navbar-brand" href="../index.html">
                <img id="logo" class="svg" src="../logo.svg" alt="">
              </a>
            </div>
            <div class="collapse navbar-collapse" id="navbar">
              <form class="navbar-form navbar-right" role="search" id="search">
                <div class="form-group">
                  <input type="text" class="form-control" id="search-query" placeholder="Search" autocomplete="off">
                </div>
              </form>
            </div>
          </div>
        </nav>
        
        <div class="subnav navbar navbar-default">
          <div class="container hide-when-search" id="breadcrumb">
            <ul class="breadcrumb">
              <li></li>
            </ul>
          </div>
        </div>
      </header>
      <div class="container body-content">
        
        <div id="search-results">
          <div class="search-list"></div>
          <div class="sr-items">
            <p><i class="glyphicon glyphicon-refresh index-loading"></i></p>
          </div>
          <ul id="pagination"></ul>
        </div>
      </div>
      <div role="main" class="container body-content hide-when-search">
        
        <div class="sidenav hide-when-search">
          <a class="btn toc-toggle collapse" data-toggle="collapse" href="#sidetoggle" aria-expanded="false" aria-controls="sidetoggle">Show / Hide Table of Contents</a>
          <div class="sidetoggle collapse" id="sidetoggle">
            <div id="sidetoc"></div>
          </div>
        </div>
        <div class="article row grid-right">
          <div class="col-md-10">
            <article class="content wrap" id="_content" data-uid="">
<h1 id="getting-started-with-docfx">Getting Started with <em>DocFX</em></h1>

<h2 id="1-what-is-docfx">1. What is <em>DocFX</em></h2>
<p><em>DocFX</em> is an API documentation generator for .NET, which currently supports C# and VB.
It generates API reference documentation from triple-slash comments in your source code.
It also allows you to use Markdown files to create additional topics such as tutorials and how-tos, and to customize the generated reference documentation.
<em>DocFX</em> builds a static HTML website from your source code and Markdown files, which can be easily hosted on any web servers (for example, <em>github.io</em>).
Also, <em>DocFX</em> provides you the flexibility to customize the layout and style of your website through templates.
If you are interested in creating your own website with your own styles, you can follow <a href="howto_create_custom_template.html">how to create custom template</a> to create custom templates.</p>
<p><em>DocFX</em> also has the following cool features:</p>
<ul>
<li>Integration with your source code. You can click &quot;View Source&quot; on an API to navigate to the source code in GitHub (your source code must be pushed to GitHub).</li>
<li>Cross-platform support. We have an exe version that runs natively on Windows and with Mono it can also run on Linux and macOS.</li>
<li>Integration with Visual Studio. You can seamlessly use <em>DocFX</em> within Visual Studio.</li>
<li>Markdown extensions. We introduced <em>DocFX Flavored Markdown(DFM)</em> to help you write API documentation. DFM is <em>100%</em> compatible with <em>GitHub Flavored Markdown(GFM)</em> with some useful extensions, like <em>file inclusion</em>, <em>code snippet</em>, <em>cross reference</em>, and <em>yaml header</em>.
For detailed description about DFM, please refer to <a href="../spec/docfx_flavored_markdown.html">DFM</a>.</li>
</ul>
<div class="WARNING">
<h5>Warning</h5>
<p><strong>Prerequisites</strong> <a href="https://www.visualstudio.com/downloads/">Visual Studio 2017</a> is needed for <code>docfx metadata</code> msbuild projects. It's not required when generating metadata directly from source code (<code>.cs</code>, <code>.vb</code>) or assemblies (<code>.dll</code>)</p>
</div>
<h2 id="2-use-docfx-as-a-command-line-tool">2. Use <em>DocFX</em> as a command-line tool</h2>
<p><em>Step1.</em> DocFX ships as a <a href="https://chocolatey.org/packages/docfx">chocolatey package</a>.
Install docfx through <a href="https://chocolatey.org/install">Chocolatey</a> by calling <code>choco install docfx -y</code>.</p>
<p>DocFX also ships as a <a href="http://brewformulas.org/docfx">Homebrew package</a>, install with <code>brew install docfx</code>.</p>
<p>Alternatively, you can download and unzip <em>docfx.zip</em> from <a href="https://github.com/dotnet/docfx/releases">https://github.com/dotnet/docfx/releases</a>, extract it to a local folder, and add it to PATH so you can run it anywhere.</p>
<p><em>Step2.</em> Create a sample project</p>
<pre><code>docfx init -q
</code></pre>
<p>This command generates a default project named <code>docfx_project</code>.</p>
<p><em>Step3.</em> Build the website</p>
<pre><code>docfx docfx_project\docfx.json --serve
</code></pre>
<p>Now you can view the generated website on <a href="http://localhost:8080">http://localhost:8080</a>.</p>
<h2 id="3-use-docfx-integrated-with-visual-studio">3. Use <em>DocFX</em> integrated with Visual Studio</h2>
<p><em>Step1.</em> Create a <strong>Class Library (.NET Framework)</strong> project</p>
<p><em>Step2.</em> Right click on the project and select <strong>Manage NuGet Package</strong></p>
<p><em>Step3.</em> Search and install the <a href="https://www.nuget.org/packages/docfx.console/"><code>docfx.console</code></a> NuGet package. It adds itself to the build targets and adds the <code>docfx.json</code> configuration file along with other files.</p>
<p><em>Step4.</em> <strong>Build</strong> the project, and a <code>_site</code> folder will be generated with the documentation.</p>
<div class="NOTE">
<h5>Note</h5>
<p><em>Possible warning</em>:</p>
<ul>
<li><p><em>Cache is corrupted</em>: if your project targets multiple frameworks, you have to indicate one to be the main for the documentation, through the <a href="https://github.com/dotnet/docfx/issues/1254#issuecomment-294080535"><code>TargetFramework</code> property</a> in <code>docfx.json</code>:</p>
<p>&quot;metadata&quot;: [
{
&quot;src&quot;: &quot;...&quot;,
&quot;dest&quot;: &quot;...&quot;,
&quot;properties&quot;: {
&quot;TargetFramework&quot;: &lt;one_of_your_framework&gt;
}
},
]</p>
</li>
</ul>
</div>
<h2 id="4-use-docfx-with-a-build-server">4. Use <em>DocFX</em> with a Build Server</h2>
<p><em>DocFX</em> can be used in a Continuous Integration environment.</p>
<p>Most build systems do not checkout the branch that is being built, but use a <code>detached head</code> for the specific commit.  DocFX needs the branch name to implement the <code>View Source</code> link in the API documentation.</p>
<p>Setting the environment variable <code>DOCFX_SOURCE_BRANCH_NAME</code> tells DocFX which branch name to use.</p>
<p>Many build systems set an environment variable with the branch name.  DocFX uses the following:</p>
<ul>
<li><code>APPVEYOR_REPO_BRANCH</code> - <a href="https://www.appveyor.com/">AppVeyor</a></li>
<li><code>BUILD_SOURCEBRANCHNAME</code> - <a href="https://www.visualstudio.com/team-services/">Visual Studio Team Services</a></li>
<li><code>CI_BUILD_REF_NAME</code> - <a href="https://about.gitlab.com/gitlab-ci/">GitLab CI</a></li>
<li><code>Git_Branch</code> - <a href="https://www.jetbrains.com/teamcity/">TeamCity</a></li>
<li><code>GIT_BRANCH</code> - <a href="https://jenkins.io/">Jenkins</a></li>
<li><code>GIT_LOCAL_BRANCH</code> - <a href="https://jenkins.io/">Jenkins</a></li>
</ul>
<div class="NOTE">
<h5>Note</h5>
<p><em>Known issue in AppVeyor</em>: Currently <code>platform: Any CPU</code> in <em>appveyor.yml</em> causes <code>docfx metadata</code> failure. <a href="https://github.com/dotnet/docfx/issues/1078">https://github.com/dotnet/docfx/issues/1078</a></p>
</div>
<h2 id="5-build-from-source-code">5. Build from source code</h2>
<p>As a prerequisite, you need:</p>
<ul>
<li><a href="https://www.visualstudio.com/vs/">Visual Studio 2017</a> with <em>.NET Core cross-platform development</em> toolset</li>
<li><a href="https://nodejs.org">Node.js</a></li>
</ul>
<p><em>Step1.</em> <code>git clone https://github.com/dotnet/docfx.git</code> to get the latest code.</p>
<p><em>Step2.</em> Run <code>build.cmd</code> under root folder.</p>
<p><em>Step3.</em> Add <code>artifacts</code> folder to nuget source by in IDE:</p>
<blockquote>
<p>Tools &gt; NuGet Package Manager &gt; Package Manager Settings &gt; Package Sources</p>
</blockquote>
<p><em>Step4.</em> Follow steps in #2, #3, #4 to use <em>DocFX</em> in command-line, IDE or .NET Core.</p>
<h2 id="6-a-seed-project-to-play-with-docfx">6. A seed project to play with <em>DocFX</em></h2>
<p>Here is a seed project: <a href="https://github.com/docascode/docfx-seed">https://github.com/docascode/docfx-seed</a>. It contains</p>
<ol>
<li>A basic C# project under <code>src</code>.</li>
<li>Several conceptual files under <code>articles</code>.</li>
<li>An overwrite file to add extra content to API under <code>specs</code>.</li>
<li><code>toc.yml</code> under root folder. It renders as the navbar of the website.</li>
<li><code>docfx.json</code> under root folder. It is the configuration file that <code>docfx</code> depends upon.</li>
</ol>
<div class="TIP">
<h5>Tip</h5>
<p>It's good practice to separate files with different types into different folders.</p>
</div>
<h2 id="7-qa">7. Q&amp;A</h2>
<ol>
<li>Q: How do I quickly reference APIs from other APIs or conceptual files?
A: Use <code>@uid</code> syntax.</li>
<li>Q: What is <code>uid</code> and where do I find <code>uid</code>?
A: Refer to <a href="../spec/docfx_flavored_markdown.html#cross-reference">Cross Reference</a> section in <a href="../spec/docfx_flavored_markdown.html">DFM</a>.</li>
<li>Q: How do I quickly find <code>uid</code> in the website?
A: In the generated website, hit F12 to view source, and look at the title of an API. You can find <code>uid</code> in <code>data-uid</code> attribute.</li>
</ol>
<div id="disqus_thread"></div>
                <script>
                (function() { // DON'T EDIT BELOW THIS LINE
                var d = document, s = d.createElement('script');
                s.src = 'https://docfx-github.disqus.com/embed.js';
                s.setAttribute('data-timestamp', +new Date());
                (d.head || d.body).appendChild(s);
                })();
                </script>
                <noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
            </article>
          </div>
          
          <div class="hidden-sm col-md-2" role="complementary">
            <div class="sideaffix">
              <div class="contribution">
                <ul class="nav">
                  <li>
                    <a href="#disqus_thread" class="contribution-link">0 Comments</a>
                  </li>
                </ul>
              </div>
              <nav class="bs-docs-sidebar hidden-print hidden-xs hidden-sm affix" id="affix">
              <!-- <p><a class="back-to-top" href="#top">Back to top</a><p> -->
              </nav>
            </div>
          </div>
        </div>
      </div>
      
      <footer>
        <div class="grad-bottom"></div>
        <div class="footer">
          <div class="container">
            <span class="pull-right">
              <a href="#top">Back to top</a>
            </span>
            <span>Copyright © 2015-2018 Microsoft<br>Generated by <strong>DocFX</strong></span>
            
          </div>
        </div>
      </footer>
    </div>
    
    <script type="text/javascript" src="../styles/docfx.vendor.js"></script>
    <script type="text/javascript" src="../styles/docfx.js"></script>
    <script type="text/javascript" src="../styles/main.js"></script>
    <script id="dsq-count-scr" src="//docfx-github.disqus.com/count.js" async=""></script>
    
    <script>
      (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
      (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
      m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
      })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
    
      ga('create', 'UA-99241001-1', 'auto');
      ga('send', 'pageview');
    
    </script>
  </body>
</html>
